OpenEdge Development:<br />ADM Reference addLink

Procedure that adds a link between two objects by setting property values in each.

A NavigationSource (toolbar) linked to a SmartBusinessObject navigates the SmartDataObject that is linked to the visual DataTarget on a paged container.

Normally addLink is run from code generated by the AppBuilder in the internal procedure adm–create–objects, in response to the developer adding links to a SmartContainer at design time. Additional calls to addLink can be written into an application when additional links are needed at run time.

If the link is not in the SupportedLinks list for either object, then the link name is treated as a single subscription in the Target for an event of that name in the Source.

If the link is in the list of PassThroughLinks, and the object at one end or the other of the new link is a SmartContainer, addLink checks to see if a link of the same type exists for that container. If so, the two links are combined, or chained together, into a single link that connects the original Source with the final Target, bypassing the Container. Refer to documentation for ADM2 or OpenEdge™ AppBuilder for more information about PassThrough links.

If the link name is of the type PageN, where N is an integer, then the caller is defining the Target to be on logical page n of the Source, which must be a SmartContainer. The addLink procedure adds the Target to the special link name PageNTargets in the Source.

For each entry in an object’s SupportedLinks, there must be a property that stores the handle(s) of the object(s) at the other end of the link, and functions to set and get that property. There must also be a property that stores a list of the named events which are associated with that link. For example, if Navigation–Source is one of a SmartPanel’s SupportedLinks, and Navigation–Target is one of a SmartDataObject’s SupportedLinks, in executing the second example above, addLink adds hdCust to the NavigationTarget property of the SmartPanel, and hSmartPanel to the NavigationSource property of the SmartDataObject. The addLink procedure checks the RETURN data type of the get property functions for these properties: a RETURN type of HANDLE means that only a single object is supported on that end of the link and that the property value is stored as a value of type HANDLE. If the RETURN type is CHARACTER, multiple objects are supported on that end of the link and the object handle is added to a property value stored as a comma-separated list of object handles. For example, the NavigationTarget property is CHARACTER, because a panel may have multiple Navigation–Targets. The NavigationSource property is HANDLE because an SmartDataObject may have only one Navigation–Source. The NavigationSourceEvents property for the SmartDataObject stores a list of the events to be subscribed to in the Source.

Examples:

/* This example defines a dynamic link from MyWindow to the SDOdCust. If the link type SpecialEvent is not defined as a SupportedLink for either SmartWindows or SmartDataObjects, then addLink will do a single SUBSCRIBE in hdCust to ‘SpecialEvent’ in hMyWindow. This means that when code in MyWindow does ‘PUBLISH ‘SpecialEvent’." The user-defined internal procedure named SpecialEvent in dCust will be executed./ RUN addLink (INPUT hMyWindow, INPUT ‘SpecialEvent’:U, INPUT hdCust). / This example will add an instance of the SupportedLink ‘Navigation’ from a SmartPanel to an SDO. Normally this link would be defined at design time and the call to addLink generated automatically by the if the SmartPanel were run after startup by application code, if response to some application event, then the link would need to be created by application code also. AddLink will SUBSCRIBE the SDO to fetchFirst, fetchNext, fetchPrev, and fetchLast in the SmartPanel, because these events are listed in the SmartPanel property NavigationSourceEvents in the SDO. */ RUN addLink (INPUT hSmartPanel, INPUT ‘Navigation’:U, INPUT hdCust).

/*  This example defines a dynamic link from MyWindow to the  
    SDOdCust. If the link type SpecialEvent is not defined as a SupportedLink 
    for either SmartWindows or SmartDataObjects, then addLink will do a 
    single SUBSCRIBE in hdCust to ‘SpecialEvent’ in hMyWindow. This means 
    that when code in MyWindow does ‘PUBLISH ‘SpecialEvent’." The  
    user-defined internal procedure named SpecialEvent in dCust will be 
    executed.*/ 
RUN addLink (INPUT hMyWindow, INPUT ‘SpecialEvent’:U, INPUT hdCust). 
/*  This example will add an instance of the SupportedLink ‘Navigation’ 
    from a SmartPanel to an SDO. Normally this link would be defined at 
    design time and the call to addLink generated automatically by the 
    if the SmartPanel were run after startup by application code, if  
    response to some application event, then the link would need to be  
    created by application code also. AddLink will SUBSCRIBE the SDO to 
    fetchFirst, fetchNext, fetchPrev, and fetchLast in the SmartPanel,  
    because these events are listed in the SmartPanel property 
    NavigationSourceEvents in the SDO. */ 
RUN addLink (INPUT hSmartPanel, INPUT ‘Navigation’:U, INPUT hdCust).